home *** CD-ROM | disk | FTP | other *** search
/ New Star Software Collection / NSS_Collection.iso / 3-170 dbase 10 for windows / 1.ima / DOC.PAK / DEBUGGER.TXT < prev    next >
Text File  |  1993-07-26  |  16KB  |  429 lines
  1. Copyright (c) 1991-1993 Borland International, Inc.  All Rights Reserved.
  2.  
  3.                                THE DBASE DEBUGGER
  4.                                ------------------
  5.  
  6. This paper contains information about how to use the BladeRunner
  7. Debugger.
  8.  
  9. TABLE OF CONTENTS
  10. -----------------
  11.  
  12. 1.  Running the Debugger
  13. 2.  Viewing source code and following program execution
  14. 3.  Viewing program files
  15. 4.  Going to a procedure
  16. 5.  Going back to the current calling command (the origin)
  17. 6.  Watching the stack
  18. 7.  Controlling program execution
  19.     a.  Animating
  20.     b.  Stepping
  21.     c.  Tracing
  22.     d.  Setting breakpoints
  23.     e.  Running a program from the Debugger
  24.     f.  Stopping program execution
  25.     g.  Resetting a program
  26. 8.  Watching expressions
  27. 9.  Changing the values of expressions you're watching
  28. 10. Inspecting variables, objects, and arrays
  29. 11. Changing the view
  30. 12. Saving and restoring Debugger configuration
  31.  
  32.  
  33. 1. Running the Debugger
  34. -----------------------
  35.  
  36. You can run the Debugger in three main ways:
  37.  
  38.      - In the Windows Program Manager, double-click the Debugger icon
  39.      - In dBASE, choose Command|Debug
  40.      - In dBASE, issue the DEBUG command in the Command window or in a
  41.        program file
  42.  
  43. Setting any of the following debugging command switches to ON opens
  44. the Debugger:
  45.  
  46.      - SET STEP
  47.      - SET ECHO
  48.      - SET TRAP
  49.  
  50.  
  51. 2. Viewing source code and following program execution
  52. ------------------------------------------------------
  53.  
  54. When you're debugging a program, its source code appears in the Module
  55. window. The name of the program replaces "No Module" as the title of the
  56. window. The current command line is highlighted. As you run the program,
  57. the source code scrolls in the window to the next line receiving program
  58. control. You can scroll the source code without affecting program
  59. execution; the next command to be executed remains highlighted.
  60.  
  61.  
  62. 3. Viewing program files
  63. ------------------------
  64.  
  65. To view any program file, choose View|File from the Debugger menu. The Select
  66. file dialog box appears, in which you can specify the file you want to view.
  67. When you click OK or press Enter, the file appears in its own window. You
  68. can scroll the file, but you can't make changes to it in the Debugger. You
  69. need to use dBASE's Editor or another editor to modify the file.
  70.  
  71.  
  72. 4.  Going to a procedure
  73. ------------------------
  74.  
  75. A Debugger feature that will be implemented in a future release is the
  76. capability to go to a procedure definition in the source code. When this
  77. feature is implemented, you will be able to use it by following these
  78. steps:
  79.  
  80.      1. Right-click the Module window.
  81.      2. Choose Goto Proc from the Module menu that appears.
  82.      3. Type the name of the procedure in the dialog box that appears and
  83.         press Enter or click OK.
  84.  
  85. 5. Going back to the current calling command (the origin)
  86. ---------------------------------------------------------
  87.  
  88. To return to the current command line in the source code, follow these
  89. steps:
  90.  
  91.      1. Right-click the Module window.
  92.      2. Choose Origin from the Module menu that appears.
  93.  
  94. The source code immediately scrolls in the Module window to bring the
  95. current command line into view.
  96.  
  97.  
  98. 6. Watching the stack
  99. ---------------------
  100.  
  101. While you run a program in the Debugger, it keeps track of any calls the
  102. program makes to other programs, procedures, or user-defined functions (UDFs)
  103. in the Stack window. When program execution stops, the Debugger updates the
  104. Stack window. Each line in the Stack window indicates the file name and line
  105. number of subroutine calls and calling routines in the order in which they
  106. were called.
  107.  
  108. You can move the Module window's focus to the location of any subroutine call
  109. by inspecting the corresponding line in the Stack window. Inspect by right-
  110. clicking the line.
  111.  
  112.  
  113. 7. Controlling program execution
  114. --------------------------------
  115.  
  116. The Debugger is your main tool for seeing what happens in your program. You
  117. have five main ways of controlling program execution from the Debugger:
  118.  
  119.      - Animating
  120.      - Stepping
  121.      - Tracing
  122.      - Setting breakpoints
  123.      - Stopping
  124.  
  125.  
  126. a. Animating
  127. ------------
  128.  
  129. You can animate your program from the Debugger, which gives you an
  130. opportunity to view the effects of each line. When you animate a program, the
  131. Debugger continuously executes the program, pausing at each command line and
  132. showing you the program's state at each line. Also at each line, the Debugger
  133. updates the Watch, Stack, and Module windows.
  134.  
  135. To animate a program, choose Run|Animate from the Debugger menu.
  136.  
  137.  
  138. b. Stepping
  139. -----------
  140.  
  141. You can run a program line by line in the Debugger and control which lines to
  142. stop at. If you don't want to stop execution within a subroutine, you can
  143. step over the command line that calls the subroutine. The call to the
  144. subroutine is still made, and the subroutine is executed; you just don't see
  145. the line-by-line execution of the subroutine. The Debugger stops at the first
  146. command line following the subroutine.
  147.  
  148. To step over a command line that calls a subroutine, do one of the following:
  149.  
  150.      - Click the Step Over icon on the SpeedBar
  151.      - Choose Run|Step Over
  152.      - Press F8
  153.  
  154.  
  155. c. Tracing
  156. ----------
  157.  
  158. To trace into a command line that calls a subroutine means to follow the
  159. execution of each line of the subroutine. The Debugger stops at the first
  160. line of the subroutine. To trace into a command line that calls a subroutine,
  161. do one of the following:
  162.  
  163.      - Click the Trace Into icon on the SpeedBar
  164.      - Choose Run|Trace Into
  165.      - Press F7
  166.  
  167.  
  168. d. Setting breakpoints
  169. ----------------------
  170.  
  171. A breakpoint is a description of a condition at which to stop program
  172. execution. That description can be one or a combination of the following:
  173.  
  174.      - A program location
  175.      - A conditional expression
  176.      - A pass count expression
  177.  
  178. To set a breakpoint in your program, do any of the following:
  179.  
  180.      - In the Module window, move the pointer to the left of the command line
  181.        to be the breakpoint and, when the pointer becomes a stop sign, click.
  182.        A line describing this breakpoint appears in the Break window. You can
  183.        move the pointer to the left of the command line again and click
  184.        again. This removes the breakpoint.
  185.  
  186.      - Move the cursor to the command line to be the breakpoint and do either
  187.        of the following:
  188.  
  189.        - Choose Break|Toggle
  190.        - Press F2
  191.  
  192.        A line describing this breakpoint appears in the Break window. You can
  193.        choose Break|Toggle or press F2 again. This removes the breakpoint.
  194.  
  195.      - Choose Break|Add from the Debugger menu and enter a breakpoint
  196.        expression, an action, command-line number, or a pass count expression
  197.        in the Add Breakpoint dialog box.
  198.  
  199.      - Right-click the Break window and enter a breakpoint expression,
  200.        action, command-line number, or a pass count expression in the Add
  201.        Breakpoint dialog box.
  202.  
  203.      - Double-click an existing breakpoint line in the Break window and enter
  204.        a breakpoint expression, action, command-line number, or a pass count
  205.        expression in the Edit Breakpoint dialog box.
  206.  
  207. The action that you can optionally specify in the Add Breakpoint and Edit
  208. Breakpoint dialog boxes is the action you want to occur when the breakpoint
  209. condition is met.
  210.  
  211.  
  212. e. Running a program from the Debugger
  213. --------------------------------------
  214.  
  215. You can run a program from the Debugger by doing one of the following:
  216.  
  217.      - Click the Run icon on the SpeedBar (the right-pointing arrow)
  218.      - Choose Run|Run from the Debugger menu
  219.      - Press F9
  220.  
  221. You can also specify that the program run until a RETURN command is
  222. encountered by choosing Run|Until Return.
  223.  
  224.  
  225. f. Stopping program execution
  226. -----------------------------
  227.  
  228. Besides adding a breakpoint, you can stop your program at any point while
  229. running it from the Debugger by doing one of the following:
  230.  
  231.      - Click the Stop icon on the SpeedBar (the Stop sign)
  232.      - Choose Run|Stop from the Debugger menu
  233.  
  234.  
  235. g. Resetting a program
  236. ----------------------
  237.  
  238. If you're running a program from the Debugger and you want to stop execution
  239. and restart (reset) the program, do one of the following:
  240.  
  241.      - Click the Reset icon on the SpeedBar (the arrow that curves to the
  242.        left)
  243.      - Choose Run|Reset from the Debugger menu
  244.  
  245. This reloads the program from disk.
  246.  
  247.  
  248. 8. Watching expressions
  249. -----------------------
  250.  
  251. Most programs contain variables for holding values and expressions that use
  252. those variables and that describe conditions. When running a program from the
  253. Debugger, you might want to watch what values get assigned to certain
  254. variables and what expressions evaluate to at certain points. Or, you might
  255. want to see what an expression using variables in the program evaluates to at
  256. certain points, even though this expression isn't in the program itself.
  257.  
  258. With dBASE's Debugger, you can watch expressions, including variables, in the
  259. Watch window. To set up a watch, do one of the following:
  260.  
  261.      - Highlight an expression, such as a variable, or move the cursor to the
  262.        expression in the source code in the Module window and do one of the
  263.        following:
  264.  
  265.            - Right-click the expression
  266.            - Choose Watch|Add
  267.            - Press Ctrl+W
  268.  
  269.        The Add Watch dialog box appears with the expression you selected.
  270.  
  271.      - Choose Watch|Add from the Debugger menu and enter the expression to
  272.        watch in the Add Watch dialog box.
  273.  
  274.      - Right-click the Watch window and enter the expression to watch in the
  275.        Add Watch dialog box.
  276.  
  277.      - Press Ctrl+W and enter the expression to watch in the Add Watch dialog
  278.        box.
  279.  
  280. The expression you specify appears in the Watch window.
  281.  
  282. To edit an existing watch description,
  283.  
  284.      - Double-click the description in the Watch window and edit it in the
  285.        Edit Watch dialog box.
  286.  
  287.      - Choose Watch|Edit from the Debugger menu and edit the description in
  288.        the Edit Watch dialog box.
  289.  
  290.  
  291. 9. Changing the values of expressions you're watching
  292. -----------------------------------------------------
  293.  
  294. In addition to watching the values of expressions, you can change these
  295. values. You might want to do this to change the course of a program. To
  296. change the value of an expression that you're currently watching in the
  297. Watch window, follow these steps:
  298.  
  299.      1. Right-click the expression in the Watch window.
  300.  
  301.      2. Choose Change from the menu that appears.
  302.  
  303.      3. Enter the value you want the expression to have in the Changing
  304.         "value" dialog box. The current value of the expression will
  305.         already be in the dialog box.
  306.  
  307. When you click OK or press Enter, the value you entered appears next to the
  308. expression in the Watch window.
  309.  
  310.  
  311. 10. Inspecting variables, objects, and arrays
  312. ---------------------------------------------
  313.  
  314. Inspecting a variable, object, or array is different from watching them.
  315. The Debugger reevaluates a watched expression at each point program
  316. execution stops. When you establish an inspection for an expression, the
  317. Debugger preserves the value of that expression at that point of program
  318. execution.
  319.  
  320. To inspect a variable, object, or array,
  321.  
  322.      - Highlight the expression (the variable, object, or array) or move the
  323.        cursor to it in the source code in the Module window and do one of
  324.        the following:
  325.  
  326.            - Right-click
  327.            - Choose Data|Inspect
  328.            - Press Ctrl+I
  329.  
  330.        The Inspect dialog box appears with the expression you selected.
  331.  
  332.      - Choose Data|Inspect from the Debugger menu and enter the expression to
  333.        inspect in the Inspect dialog box.
  334.  
  335.      - Press Ctrl+I and enter the expression to inspect in the Inspect dialog
  336.        box.
  337.  
  338. When you click OK or press Enter, the Inspecting "value" dialog box appears
  339. containing the expression you entered and its value. At this point, you can
  340. right-click the expression and its value and choose from the menu that
  341. appears:
  342.  
  343.      - Choose Range to set a range (an upper limit and lower limit value) for
  344.        the expression. The Set Range dialog box appears.
  345.  
  346.      - Choose Change to change the value of the expression. The Changing
  347.        "value" dialog box appears.
  348.  
  349.      - Choose Inspect to place the selected item in its own Inspect window.
  350.  
  351.      - Choose Descend to descend into the layers of an object, each variable
  352.        layer of which you can inspect and change.
  353.  
  354.      - Choose Hex Expand to view the contents of binary string variables.
  355.  
  356.      - Choose New Expression to inspect a different expression. The Inspect
  357.        dialog box appears.
  358.  
  359. You can also evaluate or modify an expression's value by choosing
  360. Data|Evaluate/Modify from the Debugger menu and entering the expression's
  361. value in the Evaluate dialog box.
  362.  
  363.  
  364. 11. Changing the view
  365. ---------------------
  366.  
  367. To change the window focus of the Debugger, do any of the following:
  368.  
  369.      - Click the window you want to activate
  370.      - Choose Window and then the Debugger window you want to activate
  371.      - Choose View and then the operation of the window you want to
  372.        activate
  373.  
  374. To rearrange the windows of the Debugger, do one of the following:
  375.  
  376.      - Drag them by their title bars with the mouse
  377.      - Change their size by dragging their borders
  378.      - Minimize them by clicking their minimize buttons
  379.      - Choose Window|Tile or Window|Cascade
  380.      - If one or more windows is minimized, arrange their icons by choosing
  381.        Window|Arrange Icons
  382.  
  383.  
  384. 12. Saving and restoring Debugger configuration
  385. -----------------------------------------------
  386.  
  387. Choose Options from the Debugger menu to set environment options for the
  388. Debugger and to save these settings to a .CFG file or restore options saved
  389. in an existing .CFG file.
  390.  
  391. Choose Options|Options to specify which options you want to save to a .CFG
  392. file and to move the SpeedBar. The Options dialog box appears. The
  393. configuration options you can save to a .CFG file include:
  394.  
  395.      - Desktop (the particular arrangement of the four Debugger windows and
  396.        the placement of the SpeedBar)
  397.  
  398.      - Application (the particular application to debug by default)
  399.  
  400.      - Breakpoints (the breakpoints currently set and listed in the Break
  401.        window)
  402.  
  403.      - Watchpoints (the watchpoints currently set and listed in the Watch
  404.        window)
  405.  
  406. You can turn the Debugger SpeedBar off or reposition it by clicking the
  407. following buttons in the Options dialog box:
  408.  
  409.      - Off
  410.      - Popup
  411.      - Horizontal (the original setting)
  412.      - Vertical
  413.  
  414. To specify a default drive and directory path from which to load files into
  415. the Debugger, choose Options|Path for Sources. The Path For Sources dialog
  416. box appears, in which you can enter the default path.
  417.  
  418. To save the defaults you set with the previous Options menu choices, choose
  419. Options|Save Options. The Save Configuration dialog box appears, in which you
  420. specify the name of the configuration file. The default extension is .CFG.
  421.  
  422. Once you've created a configuration file, you can restore the settings you've
  423. saved to it by choosing Options|Restore Options. The Restore Configuration
  424. dialog box appears, in which you specify the name of the existing
  425. configuration file containing the settings to restore.
  426.  
  427. To change the display font the Debugger uses, choose Options|Change Display
  428. Font. The Font dialog box appears, in which you can specify font preferences.
  429.